MBasic: Command Modifiers
Command Modifiers Introduction All internal calculations in the BasicATOM Pro are done in binary arithmetic. On the other hand, much I/O (input/output) is done in the form of ASCII characters. This includes such things as keyboard input, output to displays, etc. Atom Pro Basic provides command modifiers to convert between numeric values and ASCII, in a variety of formats. So, for example, the numeric value 21 (00010101 binary) could be output as :00010101 (binary) :%00010101 (binary with indicator) :21 (decimal) :15 (hexadecimal) :$15 (hex with indicator) There is also provision for signed and floating point numbers. All of the above are output as ASCII characters, so the number %00010101, which is a single byte in memory, is actually output as nine ASCII characters to the display, debugger, etc. Modifiers can also be used to input ASCII characters and convert them to binary numbers. Commands that Use Modifiers The following commands accept modifiers in their arguments. See the listing for each individual command for details. Modifiers can be used wherever {mods} or {modifiers} are shown in the command syntax. *Debug, debugin *Hserin, hserout *I2cin, i2cout *Owin, owout *Serin, serout *Lcdread, lcdwrite *Readdm, writedm The Examples in this Chapter To avoid confusion, for the examples in this chapter we’ll use HSERIN and HSEROUT which have the simplest syntax. Conventions Used in this Chapter Available Modifiers The following modifiers are available in Atom Basic: Output type command modifiers can also be used with the equal command and an array variable. For example: :string var byte(100) :string = "Hello World" ;string(0-10)="Hello World" :string = dec 1234567 ;string(0-6)="1234567" :string = ihex 0x3456 ;string(0-4)="$3456" etc... I/O Modifiers (HEX, DEC, BIN) Input Convert input ASCII characters to a numeric value. Input must be in hex, decimal or binary format. Important:' ASCII characters will continue to be input until an "illegal" character is received or until the specified length is reached. Any illegal character will be discarded and will terminate input. An "illegal" character is one not appropriate for the type of input, e.g. anything other than 0...9 for DEC, 0 or 1 for BIN, etc. '''''Output Convert a numeric value to ASCII characters in hex, decimal or binary format. Syntax :modifier{#max} argument{\#min} ::#max: optional maximum number of digits to pass ::#min: optional minimum number of digits to pass Examples - Input If the input is 56 (in ASCII characters) :hserin a assigns the numeric value 56 (binary 00111000) to the variable "a". If the input is 3456 (in ASCII characters) :hserin a takes the two least significant digits (56) of the input and assigns the numeric value 56 (binary 00111000) to the variable "a". Examples - Output If the numeric value of variable "a" is 1234 :hserout a ; output is 1234 in ASCII :hserout a ; output is 34 in ASCII If the value of variable "x" is 5 :hserout x\2 ; output is 05 in ASCII Note:' See also the Special Note re. Output Modifiers on page 77. I/O Modifier (STR) '''''Input Accept a variable number of values and store them in a variable array. Input is in numeric format, undelimited (i.e. bytes are expected to simply follow each other sequentially) and is not converted from ASCII. Output Output the elements of an array in numeric format. Output is not converted to ASCII characters and bytes are not delimited but simply follow each other sequentially. Syntax :str arrayname{\length{\eol}} ::length: optional maximum number of values to pass ::eol: optional end of line (EOL) character to terminate Note:' On the current versions of Basic Micro Studio, If the optional eol character is found in the input stream, it will be transfered to the array. This allows the caller to determine if the input was terminated because the maximum number of characters were input or the end of line character was processed. However on output if the input array contains the end of line character, the character will not be output. '''''Examples - Input :hserin temp\5 will accept the next 5 numeric input values and assign them to temp(0)... temp(4) :hserin temp\100\"x" will accept up to 100 input values, stopping when an "x" is input, and assign them to array "temp". Similarly, :hserin temp\100\13 will accept up to 100 input values, stopping when a carriage return (ASCII 13) is input. Example - Output :hserout temp\8 will output the first 8 values of the array "temp", beginning with temp(0). Remember that output is in numeric form, not converted to ASCII. Note:' See also the Special Note re. Output Modifiers on page 77. Signed I/O Modifiers (SHEX, SDEC, SBIN) '''''Input Convert input ASCII characters to a signed numeric value. Input must be in hex, decimal or binary format. Important:' ASCII characters will continue to be input until an "illegal" character is received. That character will be discarded and will terminate input. An "illegal" character is one not appropriate for the type of input, e.g. anything other than 0...9 for DEC, 0 or 1 for BIN, etc. '''''Output Convert a signed numeric value to ASCII characters in hex, decimal or binary format. Syntax :modifier{#max} argument{\#min} ::#max: optional maximum number of digits to pass ::#min: optional minimum number of digits to pass Examples - Input If the input is -56 (in ASCII characters) :hserin a assigns the numeric value -56 to the variable "a". If the input is -3f (in ASCII characters) :hserin a assigns the numeric value -56 (expressed in decimal) to the variable "a". Examples - Output If the value of variable "a" is -1234 (decimal) or -4d2 (hex) :hserout a ; output is -1234 in ASCII :hserout a ; output is -D2 in ASCII If the value of variable "x" is 5 :hserout x\2 ; output is +05 in ASCII Note:' See also the Special Note re. Output Modifiers on page 77. Indicated I/O Modifiers (IHEX, IBIN) Indicated I/O modifiers are almost identical in both syntax and operation to the unsigned and signed modifiers described on the previous two pages.'' '''''Input ASCII characters are converted to an unsigned numeric value. Input characters are ignored until a valid indicator ($ for hex, % for binary) is received. Important:' ASCII characters will continue to be input until an "illegal" character is received. That character will be discarded and will terminate input. An "illegal" character is one not appropriate for the type of input, e.g. anything other than 0...9 for DEC, 0 or 1 for BIN, etc. '''''Output An unsigned numeric value is converted to ASCII characters preceded by an indicator ($ for hex, % for binary). Syntax :modifier{#max} argument{\#min} ::#max: optional maximum number of digits to pass ::#min: optional minimum number of digits to pass Examples - Input If the input is $A3FC :hserin a will assign the numeric value $A3FC (41980 decimal) to variable "a". Note:' An input of "The value is $A3FC" will ignore all characters prior to the $ and give the same result as above. :hserin a will assign the numeric value $FC (252 decimal) to variable "a". '''''Examples - Output If the numeric value of "a" is 41980 (decimal) or $A4FC (hex): :hserout a ; output is $A4FC in ASCII :hserout a ; output is $FC in ASCII If the numeric value of "x" is 5 :hserout x ; output is %101 in ASCII :hserout x\8 ; output is %00000101 in ASCII Note:' See also the Special Note re. Output Modifiers on page 77. Combination I/O Modifiers (ISHEX, ISBIN) Combination I/O modifiers have the characteristics of both Indicated and Signed modifiers, as described in the previous section. '''''Syntax For syntax see the previous sections. Examples - Input If the input is $-3FC :hserin a will assign the numeric value $-3FC (-1020 decimal) to variable "a". Examples - Output If the numeric value of "a" is -41980 (decimal) or $A4FC (hex): :hserout a ; output is $-A4FC in ASCII :hserout a\8 ; output is $-11111100 in ASCII (these are the low 8 bits i.e. 2 hex digits of the value). Note:' See also the Special Note re. Output Modifiers on page 77. Output Only Modifiers (REAL, REP) REAL Converts a floating point value to ASCII characters, including sign and decimal point. '''''Syntax :real{#maxb} argument{\#maxa} ::#maxb: optional maximum number of digits to pass before decimal point (default 10) ::#maxa: optional maximum number of digits to display after decimal point (default 10) Examples If variable "y" contains the floating point value 123.45: :hserout y will send the ASCII characters 123.4500000000 to the hardware serial port. :hserout y will send the ASCII characters 23.4500000000 to the hardware serial port :hserout y\2 will send the ASCII characters 123.45 to the hardware serial port. :hserout y\1 will send the ASCII characters 123.4 to the hardware serial port (the number is truncated, not rounded). Note:' See also the Special Note re. Output Modifiers on page 77. REP Repeats a character multiple times. '''''Syntax :rep argument\n ::n is the number of repetitions Example :hserout "-"\20 will output the - character 20 times (could be used for underlining, as an example). Special Note re. Output Modifiers In addition to the examples given previously in this section, output modifiers can be used in assignment statements (e.g. a = b) to assign decimal, hex or binary ASCII characters or strings of characters to a variable or array. Examples If "x" and "y" are byte variables, and "y" contains the numeric value 8, then: :x = hex1 y will assign the value 56 (which is the ASCII character for the number "8") to "x". Important:' If the numeric value would result in a 2 or more digit ASCII number (including sign or indicator), the target variable ("x" in the above example) should be defined as an array. For example, :var byte x(3) :x = dec3 y would allow "x" to hold up to 3 decimal digits, covering all possible values of a single byte variable. Add an extra byte to "x" if you use a signed or indicated modifier, and two extra bytes if you use a combination modifier. So if "y" held the hex value $-4D :var byte x(4) :x = ishex2 y would assign the values $24, $2D, $34 and $44 to successive locations of "x" (these are the ASCII values corresponding to $-4D). '''''Using REP to Preset an Array The REP modifier can also be used to pre-set an array to any desired value. For example, :var byte a(20) :a = rep 0\20 will set all 20 elements of "a" to the numeric value 0 (zero). If you were, instead, to use :var byte a(20) :a = rep "0"\20 all 20 elements of "a" would be set to the numeric value 48 (i.e. the ASCII value of the character "0" (zero). Input-only Modifiers (WAITSTR, WAIT, SKIP) WAITSTR Receives data until a continuous group matches the string contained in an array variable. Syntax :waitstr string\length{\eol} ::string is the array to use for matching purposes ::length is the number of characters to match ::eol is the End Of Line character to watch for Example The following program excerpt will accept input from the hardware serial port until the characters "e", "n", "d" are received in sequence, or until an end of line (Carriage Return) character is received. :var byte x(30) :var byte y(3) :y = "end" ::; this puts the ASCII characters ::; e, n, and d into y(0), y(1) and ::; y(2) respectively :hserin y\3\13 x ; 13 is the CR character WAIT Receives data until a continuous group matches the string constant included in the modifier. WAIT is similar to WAITSTR except a string constant, rather than a pre-defined array, is used for matching. Syntax :wait("constant string") Example The following program excerpt has a similar function to that shown in the previous section, except that an EOL test is not performed. :var byte a(30) :hserin wait("end") ; parentheses are required ??? WHERE IS variable a in the command ??? This program will accept input data for the array "a" until the three characters "e", "n" and "d" are received in sequence. SKIP Skips a specified number of input values. This is useful if your data is preceded by a label that should not be input. Syntax :skip count ::count is the number of bytes to skip Example The following program excerpt inputs a two digit temperature and saves it as a numeric value.. Actual input has the format: :temperature: nn where nn is the two digit temperature in decimal ASCII. :var byte temp :hserin 13,a ::; "temperature: " is 13 ::; characters long :hserin a